home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / CrtSelHdlr.3 < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tk_CreateSelHandler(3)Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_CreateSelHandler, Tk_DeleteSelHandler - arrange to handle
  12.      requests for the primary selection
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_CreateSelHandler(_t_k_w_i_n, _t_a_r_g_e_t, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _f_o_r_m_a_t)
  18.  
  19.      Tk_DeleteSelHandler(_t_k_w_i_n, _t_a_r_g_e_t)
  20.  
  21. ARGUMENTS
  22.      Tk_Window          _t_k_w_i_n        (in)      Window  for  which
  23.                                                _p_r_o_c  will provide
  24.                                                selection informa-
  25.                                                tion.
  26.  
  27.      Atom               _t_a_r_g_e_t       (in)      Form in which _p_r_o_c
  28.                                                can   provide  the
  29.                                                selection    (e.g.
  30.                                                STRING          or
  31.                                                FILE_NAME).
  32.                                                Corresponds     to
  33.                                                _t_y_p_e arguments  in
  34.                                                selection     com-
  35.                                                mands.
  36.  
  37.      Tk_SelectionProc   *_p_r_o_c        (in)      Procedure       to
  38.                                                invoke    whenever
  39.                                                the  selection  is
  40.                                                owned by _t_k_w_i_n and
  41.                                                the selection con-
  42.                                                tents          are
  43.                                                requested  in  the
  44.                                                format   given  by
  45.                                                _t_a_r_g_e_t.
  46.  
  47.      ClientData         _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary one-word
  48.                                                value  to  pass to
  49.                                                _p_r_o_c.
  50.  
  51.      Atom               _f_o_r_m_a_t       (in)      If  the  selection
  52.                                                requestor isn't in
  53.                                                this process, _f_o_r_-
  54.                                                _m_a_t determines the
  55.                                                representation
  56.                                                used  to  transmit
  57.                                                the  selection  to
  58.                                                its requestor.
  59. _________________________________________________________________
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_CreateSelHandler(3)Tk Library Procedures
  71.  
  72.  
  73.  
  74. DESCRIPTION
  75.      Tk_CreateSelHandler  arranges  for  a  particular  procedure
  76.      (_p_r_o_c) to be called whenever the selection is owned by _t_k_w_i_n
  77.      and the selection contents are requested in the  form  given
  78.      by  _t_a_r_g_e_t.   _T_a_r_g_e_t should be one of the entries defined in
  79.      the left column of Table 2 of the X Inter-Client  Communica-
  80.      tion  Conventions  Manual (ICCCM) or any other form in which
  81.      an application is willing to  present  the  selection.   The
  82.      most common form is STRING.
  83.  
  84.      _P_r_o_c should have arguments and result that  match  the  type
  85.      Tk_SelectionProc:
  86.           typedef int Tk_SelectionProc(
  87.                ClientData _c_l_i_e_n_t_D_a_t_a,
  88.                int _o_f_f_s_e_t,
  89.                char *_b_u_f_f_e_r,
  90.                int _m_a_x_B_y_t_e_s);
  91.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  92.      argument  given  to Tk_CreateSelHandler.  Typically, _c_l_i_e_n_t_-
  93.      _D_a_t_a points to  a  data  structure  containing  application-
  94.      specific  information  that is needed to retrieve the selec-
  95.      tion.  _O_f_f_s_e_t specifies an offset position into  the  selec-
  96.      tion,  _b_u_f_f_e_r specifies a location at which to copy informa-
  97.      tion about the selection, and _m_a_x_B_y_t_e_s specifies the  amount
  98.      of  space  available  at  _b_u_f_f_e_r.  _P_r_o_c should place a NULL-
  99.      terminated string at _b_u_f_f_e_r  containing  _m_a_x_B_y_t_e_s  or  fewer
  100.      characters  (not  including  the  terminating  NULL), and it
  101.      should return a count of the number of  non-NULL  characters
  102.      stored  at  _b_u_f_f_e_r.  If the selection no longer exists (e.g.
  103.      it once existed but the user deleted the range of characters
  104.      containing it), then _p_r_o_c should return -1.
  105.  
  106.      When transferring large selections, Tk will  break  them  up
  107.      into  smaller  pieces  (typically a few thousand bytes each)
  108.      for more efficient transmision.  It will do this by  calling
  109.      _p_r_o_c  one or more times, using successively higher values of
  110.      _o_f_f_s_e_t to retrieve successive portions of the selection.  If
  111.      _p_r_o_c  returns  a  count less than _m_a_x_B_y_t_e_s it means that the
  112.      entire remainder of the selection  has  been  returned.   If
  113.      _p_r_o_c's  return value is _m_a_x_B_y_t_e_s it means there may be addi-
  114.      tional information in the selection, so Tk must make another
  115.      call to _p_r_o_c to retrieve the next portion.
  116.  
  117.      _P_r_o_c always returns selection information in the form  of  a
  118.      character string.  However, the ICCCM allows for information
  119.      to be transmitted from the selection owner to the  selection
  120.      requestor  in  any  of several formats, such as a string, an
  121.      array of atoms, an array of integers, etc.  The _f_o_r_m_a_t argu-
  122.      ment  to Tk_CreateSelHandler indicates what format should be
  123.      used to transmit the selection to  its  requestor  (see  the
  124.      middle  column  of  Table  2 of the ICCCM for examples).  If
  125.      _f_o_r_m_a_t is not STRING, then Tk will take the  value  returned
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tk_CreateSelHandler(3)Tk Library Procedures
  137.  
  138.  
  139.  
  140.      by _p_r_o_c and divided it into fields separated by white space.
  141.      If _f_o_r_m_a_t is ATOM, then Tk will return the selection  as  an
  142.      array  of atoms, with each field in _p_r_o_c's result treated as
  143.      the name of one atom.  For any other  value  of  _f_o_r_m_a_t,  Tk
  144.      will return the selection as an array of 32-bit values where
  145.      each field of _p_r_o_c's result  is  treated  as  a  number  and
  146.      translated to a 32-bit value.  In any event, the _f_o_r_m_a_t atom
  147.      is returned to the selection requestor along with  the  con-
  148.      tents of the selection.
  149.  
  150.      If Tk_CreateSelHandler is called when there already exists a
  151.      handler  for  _t_a_r_g_e_t  on _t_k_w_i_n, then the existing handler is
  152.      replaced with a new one.
  153.  
  154.      Tk_DeleteSelHandler removes the handler given by  _t_k_w_i_n  and  |
  155.      _t_a_r_g_e_t,  if  such  a  handler  exists.   If there is no such  |
  156.      handler then it has no effect.
  157.  
  158.  
  159. KEYWORDS
  160.      format, handler, selection, target
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.